Nano Banana CLI Tool — Generate and edit images with the power of Google Gemini models directly from your terminal.
nb-cli is a lightweight command-line interface for the Nano Banana (Gemini 3.1 Flash Image Preview) model. It allows you to create high-quality images from text prompts and perform sophisticated image editing by providing natural language instructions alongside an existing image.
Use .jpg output filenames when you pass -o. If you omit the extension, nb-cli will save using the model's native output format automatically.
- Node.js (v18+)
- Google Gemini API Key
Using NPM (Global):
npm install -g @crapthings/nb-cliUsing NPX (No installation):
npx @crapthings/nb-cli generate "A futuristic banana"From Source:
git clone https://github.com/crapthings/nb-cli.git
cd nb-cli
npm install
npm link # To use 'nb' command locallyTo use this CLI, you need a Google Gemini API Key.
- Get one for free at: Google AI Studio
Set the key in your shell environment:
export GEMINI_API_KEY=your_api_key_hereCreate a brand new image from a text prompt.
nb generate "A cyberpunk cat sitting on a neon-lit skyscraper" -o cyber-cat.jpg -s 1k -a 16:9Generate a 1:1 minimalist icon for a given prompt. This command automatically adds icon-specific keywords to your prompt.
nb icon "a playful banana" -o banana-icon.jpgModify an existing image by describing the changes you want.
nb edit cyber-cat.jpg "Make the cat wearing sunglasses and drinking a soda" -o edit.jpg -a 1:1When you're building a website or web app with tools like Codex or Claude Code, nb-cli is a fast way to generate hero images, landing page artwork, blog thumbnails, feature illustrations, and other visual assets without leaving the terminal.
Example workflow:
nb generate "A clean SaaS dashboard hero image with floating analytics cards, soft daylight, modern editorial composition" -o hero.jpg -s 2k -a 16:9You can then drop the generated image straight into your repo while your coding agent continues implementing the page.
If you use Codex skills, you can install the bundled nb-cli skill from this repo with:
npx skills add https://github.com/crapthings/nb-cli --skill nb-cliThis installs the nb-cli skill so your agent can use the CLI with the repo's prompt guidance and image-generation references.
After installation, trigger it with requests such as:
Use $nb-cli to generate a 16:9 SaaS hero image with soft daylight and editorial compositionUse $nb-cli to create a minimalist coffee cup icon for my appUse $nb-cli to edit hero.jpg and change only the background to a warm sunset gradientUse $nb-cli to generate a product mockup for a matte black bottle, centered three-quarter angle, soft studio light
Shout-out to grokfilm.app. The still-image technique references in the bundled skill were inspired by the film and photography technique vocabulary collected there.
| Option | Short | Description | Default |
|---|---|---|---|
--output |
-o |
Path to save the resulting image. Use a .jpg filename, or omit the extension to use the model's native format automatically. |
6-char-nanoid.jpg |
--size |
-s |
Image resolution (512, 1k, 2k, 4k) | 512 |
--aspect-ratio |
-a |
Image aspect ratio (21:9, 16:9, 1:1, etc.) | 1:1 |
Ordered by the leading dimension (width) from largest to smallest:
- Horizontal:
21:9,16:9,8:1,5:4,4:3,4:1,3:2 - Square:
1:1 - Vertical:
9:16,4:5,3:4,2:3,1:4,1:8
- Use
.jpgfor output files, including with-o. - PNG, WEBP, and other output formats are not supported in this CLI.
- If you leave the extension off,
nb-cliwill append the model's actual output format.
bin/nb.js: Entry point for the CLI tool.src/api.js: Interactions with the Google Gemini (Nano Banana) API.src/commands.js: Command handlers forgenerateandedit.test/: Unit tests usingmochaandchai.AGENTS.md: Technical overview and project requirements.
This project follows the StandardJS coding style.
- No semicolons.
- 2-space indentation.
- High-quality, idiomatic JavaScript.
The project uses mocha and chai for unit testing.
npm testnpm run lintLicensed under the MIT License.